Quarto/RMarkdown - What’s Different?

FCT Abuja useR Group

Ted Laderas

9/15/2022

Agenda for Today

  • What is Quarto?
  • Should you switch from RMarkdown?
    • Demo
  • Guide to Converting RMarkdown
  • Questions

About Me

  • RStudio Academy Data Science Mentor
  • RStudio/Carpentries Certified Instructor
  • Bioinformatics Trainer at DNAnexus
  • Twitter: @tladeras
  • Web: https://laderast.github.io/

What is Quarto?

RStudio Conference 2022

What is Quarto?

  • Reproducible Publishing System based on Pandoc
  • One format, many outputs
    • Website
    • Publications
    • Books
    • Dashboards

.qmd files

  • Short for quarto markdown
  • Decoupled from RStudio IDE
    • plugins for VSCode, JupyterLab and RStudio are available
  • Can still Render within RStudio
  • Render with quarto standalone on command line:
quarto render my_document.qmd

Cross Language Support

Jupyter Notebook Support

quarto convert notebook.ipynb

Fast way to publish Jupyter Notebooks!

Code Output Freezing

  • By default, code is not recomputed
  • quarto render --execute will recompute
  • Output is “frozen”
execute:
  freeze: auto  # re-render only when source changes

Code Chunks

Options are moved to within the code chunk using #| (hash-pipe) for each line

RMarkdown

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```

Quarto

```{r}
#| label = "setup",
#| include = FALSE
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```

What’s Different with Quarto?

How is Quarto different from RMarkdown?

  • Standardized YAML across formats
  • Decoupled from RStudio
  • More consistent presentation across formats
  • Tab Panels
  • Code Highlighting

Should I Switch to Quarto?

Should you switch to Quarto? Not necessarily. If you find R Markdown meet your need, you can definitely stay there. It is not imperative to switch. Quarto’s goal is to cover most features of R Markdown eventually, but it may be impossible to become a strict superset of R Markdown. - Yihui Xie

Some Killer Apps for Quarto (HTML)

  • Precise Layouts
  • Tab Panels
  • Code Highlighting

Layout Example

:::: {.columns}

::: {.column width="50%"}
- Highly customizable
- Less work than using `<div>` tags
:::

::: {.column width="50%"}
- Customizable in terms of layouts

:::
::::

Layout Example

  • Highly customizable
  • Less work than using <div> tags
  • Customizable in terms of layouts

Tabsets

::: {.panel-tabset}

### Code

This is where I would put some code:

### Figure

:::

Tabsets

This is where I would put some code:

```{r}
library(palmerpenguins)
library(ggplot2)
data(penguins)
ggplot(penguins, aes(x=bill_depth_mm, y=bill_length_mm, color = species)) + geom_point()
```

Code Highlighting

  • Incremental highlighting (line by line)
  • Killer app for me
  • Really good for teaching!
```{r}
#| echo: TRUE
#| eval: FALSE
#| code-line-numbers: "3|4-6|7"
library(palmerpenguins)
library(ggplot2)
data(penguins)
ggplot(penguins) + aes(x=bill_depth_mm, 
                       y=bill_length_mm, 
                       color = species) + 
  geom_point()
```

Code Highlighting Example

library(palmerpenguins)
library(ggplot2)
data(penguins)
ggplot(penguins) + aes(x=bill_depth_mm, 
                       y=bill_length_mm, 
                       color = species) + 
  geom_point()

How to move to Quarto

Checklist

  1. Start a Quarto Project
  2. For your documents: Change your output: to the corresponding format: in your YAML
  3. Use knitr::convert_chunk_header() to convert your code blocks (outputs a .qmd file)
  4. Render your files
  5. For websites: edit your _quarto.yml file if necessary

1. Start a Quarto Project

File > New Project > New Directory > Quarto Project

Quarto Project Start

2. Convert your Rmarkdown Documents

  • Change your YAML header
  • Instead of output:, use format:

---
title: "Quarto/RMarkdown - What's Different?"
author: Ted Laderas
subtitle: FCT Abuja useR Group
date: 9/15/2022
output:
  xaringan::moon_reader:
    lib_dir: libs
    css: xaringan-themer.css
---

---
title: "Quarto/RMarkdown - What's Different?"
author: Ted Laderas
subtitle: FCT Abuja useR Group
date: 9/15/2022
format: 
  revealjs:
    self-contained: true
    theme: night
    footer: <https://laderast.github.io/qmd_rmd/>
incremental: false
highlight-style: github
---

2. RMarkdown/Quarto Formats

RMarkdown Quarto
output: html_document format: html
output: pdf_document format: pdf
output: word_document format: docx
output: xaringan format: revealjs
output: ioslides format: revealjs
output: distill Quarto Article Layout

3. Convert your RMarkdown Code Chunks

knitr::convert_chunk_header() will convert your RMarkdown code chunks into quarto compatible format.

knitr::convert_chunk_header("filename.Rmd", 
    output = "filename.qmd")

3. Converting Code Chunks

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```
```{r}
#| label = "setup",
#| include = FALSE
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```

4. Render via RStudio GUI

  • Render button in RStudio
quarto::quarto_render()`

4. Render via Command Line

> quarto render <filename>

5. Update your _quarto.yml for websites

project:
  type: website

website:
  title: "Ted Laderas, PhD"
  description: "Ted's R and Teaching Blog"
  navbar:
    right:
      - teaching.qmd
      - articles.qmd
      - blog.qmd
      - talks.qmd

Publish your files (on CLI)

quarto publish can push and update a number of different kinds of webhosts.

quarto publish gh-pages    # GitHub Pages
quarto publish quarto-pub  # Quarto.pub 
quarto publish netlify     # Netlify
quarto publish connect     # RStudio Connect

Conclusions

  • Quarto supports multiple languages / IDEs
  • Quarto standardizes a lot of outputs
  • Does a better job of one document, many outputs
  • Lots of publishing features (references, figures, etc.)

Learn More

Workshop materials from Andrew Bray: https://github.com/rstudio-conf-2022/rmd-to-quarto

Thank You! Questions?

Extras

Observable + Shiny + Quarto

  • Rapid prototyping of responsive dashboards
  • Uses Observable for front end
  • Uses Shiny reactives for backend
  • Quarto for Layout